home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / msdos / animutil / fastgfx / fg303b / manuals.arj / USER16.DOC < prev    next >
Encoding:
Text File  |  1993-10-02  |  7.8 KB  |  198 lines
  1. Chapter 16
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Program Timing
  8.  
  9. 300   Fastgraph User's Guide
  10.  
  11.  
  12.  
  13. Overview
  14.  
  15.      It is occasionally necessary to delay a program's execution for a brief
  16. period, or to determine how long it takes to execute specific sections of a
  17. program.  Fastgraph includes routines to accomplish these tasks.  Some of
  18. these routines are said to be real-time, which means they are independent of
  19. a system's processor speed, while the speed of others is processor-specific.
  20. This chapter describes both classes of timing routines, all of which are
  21. independent of the other parts of Fastgraph.
  22.  
  23.  
  24. Real-Time Routines
  25.  
  26.      Real-time operations center around the BIOS time-of-day clock, which is
  27. nothing more than a counter that the system automatically increments 18.2
  28. times per second.  This number is often called the clock tick interrupt rate
  29. because an interrupt routine performs the incrementing.  In addition, each
  30. increment is usually called a clock tick.
  31.  
  32.      The Fastgraph routine fg_waitfor delays a program's execution by the
  33. number of clock ticks specified as its argument.  Because fg_waitfor uses
  34. clock ticks, the actual length of the delay is the same, regardless of the
  35. system's processor speed.  Even when Fastgraph's asynchronous sound routines
  36. quadruple the clock tick interrupt rate, Fastgraph compensates for this
  37. internally so fg_waitfor always works as though the actual rate were still
  38. 18.2 times per second.
  39.  
  40.      Example 16-1 displays a message every five seconds that states how long
  41. the program has been running.  The fg_waitfor routine produces the five-
  42. second delay by pausing 91 (18.2 times 5) clock ticks before the program
  43. displays each message.  The program returns to DOS when you press any key.
  44.  
  45.                                 Example 16-1.
  46.  
  47.              #include <fastgraf.h>
  48.              #include <stdio.h>
  49.              void main(void);
  50.  
  51.              void main()
  52.              {
  53.                 unsigned int seconds;
  54.                 unsigned char key, aux;
  55.  
  56.                 seconds = 0;
  57.  
  58.                 do {
  59.                    fg_waitfor(91);
  60.                    seconds += 5;
  61.                    printf("%u seconds have elapsed.\n",seconds);
  62.                    fg_intkey(&key,&aux);
  63.                 }
  64.                 while (key+aux == 0);
  65.              }
  66.  
  67.                                              Chapter 16:  Program Timing   301
  68.  
  69.  
  70.      Another common application of the fg_waitfor routine is to slow down a
  71. loop that uses the fg_intkey routine to check for keystrokes.  In loops that
  72. do little else, we may call fg_intkey too rapidly without this delay, and it
  73. is then possible that the BIOS may not be able to store characters in its
  74. keyboard buffer fast enough.  A small delay, even one clock tick, often helps
  75. such "tight" loops.
  76.  
  77.      The fg_getclock routine provides an efficient way to measure time,
  78. especially differences in time.  This routine has no arguments and returns a
  79. 32-bit unsigned integer (as its function value) representing the number of
  80. clock ticks since midnight.  Example 16-2 demonstrates the fg_getclock
  81. routine.  In response to any keystroke (except Escape, which returns control
  82. to DOS), the program displays the number of clock ticks since midnight, and
  83. the number of ticks since the program started.
  84.  
  85.                                 Example 16-2.
  86.  
  87.       #include <fastgraf.h>
  88.       #include <stdio.h>
  89.       void main(void);
  90.  
  91.       #define ESC 27
  92.  
  93.       void main()
  94.       {
  95.          unsigned long start, ticks;
  96.          unsigned char key, aux;
  97.  
  98.          start = fg_getclock();
  99.  
  100.          do {
  101.             ticks = fg_getclock();
  102.             printf("%lu ticks since midnight.\n",ticks);
  103.             printf("%lu ticks since start of program.\n\n",ticks-start);
  104.             fg_getkey(&key,&aux);
  105.          }
  106.          while (key != ESC);
  107.       }
  108.  
  109.  
  110.  
  111. Routines Dependent on the System Speed
  112.  
  113.      The fg_waitfor routine described in the previous section is independent
  114. of the system's processor speed.  This means the actual length of its delay
  115. is the same on any system.  Another routine, fg_stall, is similar to
  116. fg_waitfor, but its delay is proportional to the processor speed.  Like
  117. fg_waitfor, fg_stall has a single integer argument that specifies the length
  118. of the delay.  However, instead of being expressed in clock ticks, fg_stall
  119. measures the delay in delay units.  The fg_stall routine treats the length as
  120. an unsigned quantity, so the maximum number of delay units we can specify is
  121. 65,535.  The following table lists the approximate number of delay units per
  122. clock tick on three typical systems.
  123. 302   Fastgraph User's Guide
  124.  
  125.                       system       delay units
  126.                        type      per clock tick
  127.  
  128.                    Tandy 1000 HX       280
  129.                    25 MHz 80386       3,400
  130.                    40 MHz 80386       7,100
  131.  
  132.      Fastgraph includes a routine that determines the number of delay units
  133. per clock tick for the processor being used.  This is the fg_measure routine,
  134. which has no arguments and returns the number of delay units per clock tick
  135. as its function value.  Once we determine this value, we can use fg_stall to
  136. delay a program's execution in real time.  This provides a much more refined
  137. delay than the clock tick unit used by fg_waitfor.
  138.  
  139.      Example 16-3 is functionally identical to example 16-1, but it uses the
  140. fg_stall routine instead of fg_waitfor to delay the program execution.  The
  141. program first calls the fg_measure routine to determine number of delay units
  142. equivalent to one clock tick.  It then passes this value to fg_stall, called
  143. 91 times inside the for loop to create the five-second delay (because 91
  144. clock ticks equals five seconds).  The program returns to DOS when you press
  145. any key.
  146.  
  147.                                 Example 16-3.
  148.  
  149.              #include <fastgraf.h>
  150.              #include <stdio.h>
  151.              void main(void);
  152.  
  153.              void main()
  154.              {
  155.                 int i;
  156.                 int units_per_tick;
  157.                 unsigned int seconds;
  158.                 unsigned char key, aux;
  159.  
  160.                 seconds = 0;
  161.  
  162.                 printf("Benchmarking system speed...\n");
  163.                 units_per_tick = fg_measure();
  164.                 printf("Benchmark completed.\n\n");
  165.  
  166.                 do {
  167.                    for (i = 0; i < 91; i++)
  168.                       fg_stall(units_per_tick);
  169.                    seconds += 5;
  170.                    printf("%u seconds have elapsed.\n",seconds);
  171.                    fg_intkey(&key,&aux);
  172.                 }
  173.                 while (key+aux == 0);
  174.              }
  175.  
  176.  
  177.      One final point:  the fg_measure routine takes a few seconds to
  178. benchmark the system speed accurately.  For this reason, you should only call
  179. fg_measure once (typically at the beginning of the program) and use its
  180. return value instead of calling fg_measure throughout the program.
  181.                                             Chapter 16:  Program Timing   302A
  182.  
  183.  
  184. Summary of Timing Routines
  185.  
  186.      This section summarizes the functional descriptions of the Fastgraph
  187. routines presented in this chapter.  More detailed information about these
  188. routines, including their arguments and return values, may be found in the
  189. Fastgraph Reference Manual.
  190.  
  191.      FG_GETCLOCK returns the number of clock ticks since midnight as its
  192. function value.  This quantity is a 32-bit unsigned integer.
  193.  
  194.      FG_MEASURE returns the approximate number of delay units per clock tick
  195. as its function value.  This quantity is proportional to the system's
  196. processor speed.
  197.  
  198.      FG_STALL delays a program's execution for a given number of processor-
  199. specific delay units.
  200.  
  201.      FG_WAITFOR delays a program's execution for a given number of clock
  202. ticks.  There are 18.2 clock ticks per second, regardless of the system's
  203. processor speed.
  204.